<!DOCTYPE HTML>
<html lang="en">
<head>
<title>#Warn - Syntax &amp; Usage | AutoHotkey</title>
<meta name="description" content="The #Warn directive enables or disables warnings for specific conditions which may indicate an error, such as a typo or missing &quot;global&quot; declaration." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>#Warn <span class="ver">[v1.0.95.00+]</span></h1>

<p>Enables or disables warnings for specific conditions which may indicate an error, such as a typo or missing "global" declaration.</p>

<pre class="Syntax"><span class="func">#Warn</span> <span class="optional">WarningType, WarningMode</span></pre>

<h2>Parameters</h2>
<dl>

  <dt>WarningType</dt>
  <dd>
      <p>The type of warning to enable or disable. If omitted, it defaults to <i>All</i>.</p>
      <p id="UseUnset"><strong>UseUnsetLocal</strong> or <strong>UseUnsetGlobal</strong>: Warn when a variable is read without having previously been assigned a value or initialized with <a href="VarSetCapacity.htm">VarSetCapacity()</a>.  If the variable is intended to be empty, assign an empty string to suppress this warning.</p>
      <p>This is split into separate warning types for locals and globals because it is more common to use a global variable without prior initialization, due to their persistent and script-wide nature.  For this reason, some script authors may wish to enable this type of warning for locals but disable it for globals.</p>
      <pre>#Warn
<em>;y := ""  ; This would suppress the warning.</em>
x := y    <em>; y hasn't been assigned a value.</em></pre>
      <p id="UseEnv"><strong>UseEnv</strong>: Warn when an environment variable is automatically used in place of an empty script variable.  This sometimes occurs when an environment variable's name unexpectedly matches a variable used by the script.  This warning occurs when the variable is accessed, but never occurs if the script enables <a href="_NoEnv.htm">#NoEnv</a> (recommended for multiple reasons).</p>
      <pre>#Warn
<em>;#NoEnv             ; Add this if "temp" is not intended to be an environment variable.</em>
<em>;EnvGet temp, TEMP  ; This would copy the environment variable's value into the script variable.</em>
temp := ""          <em>; Despite this line, temp still seems to have a value.</em>
MsgBox % temp       <em>; This accesses the environment variable named "TEMP".</em></pre>
      <p id="LocalSameAsGlobal"><strong>LocalSameAsGlobal</strong>: Before the script starts to run, display a warning for each <em>undeclared</em> local variable which has the same name as a global variable.  This is intended to prevent errors caused by forgetting to declare a global variable inside a function before attempting to access it.  If the variable really was intended to be local, a declaration such as <code>local x</code> or <code>static y</code> can be used to suppress the warning.  This warning is never shown for variables inside a <a href="../Functions.htm#ForceLocal">force-local</a> function.</p>
      <pre>#Warn
g := 1
ShowG() {       <em>; The warning is displayed even if the function is never called.</em>
    <em>;global g   ; &lt;-- This is required to access the global variable.</em>
    MsgBox % g  <em>; Without the declaration, "g" is an empty local variable.</em>
}</pre>
      <p id="ClassOverwrite"><strong>ClassOverwrite</strong> <span class="ver">[v1.1.27+]</span>: Before the script starts to run, show a warning for each assignment targetting a class variable. For example, <code>box := new Box</code> will show a warning if <em>Box</em> is a class, since this would overwrite the class (within the super-global variable, <em>Box</em>). Warnings are also shown for output variables of commands, but not ByRef parameters. Warnings are not shown for nested classes or dynamic variable references.</p>
      <p id="Unreachable"><strong>Unreachable</strong> <span class="ver">[v1.1.33+]</span>: Before the script starts to run, show a warning for each line that immediately follows a <code>Return</code>, <code>Break</code>, <code>Continue</code>, <code>Throw</code>, <code>Goto</code> or <code>Exit</code> at the same nesting level, unless that line is the target of a label. Although this does not detect all unreachable code, it detects common errors such as:</p>
      <ul>
        <li>Placing initialization code (such as an assignment or <a href="GroupAdd.htm">GroupAdd</a>) in between hotkey subroutines, when it should be in the <a href="../Language.htm#auto-execute-section">auto-execute section</a>.</li>
        <li>Placing the first line of a "multi-line" hotkey subroutine on the same line as the hotkey label. Doing so will make it a <a href="../Hotkeys.htm#Intro">single-line hotkey</a>, with an implicit <code>return</code> that prevents any subsequent lines from executing. Similarly, placing <code>return</code> after a single-line hotkey is redundant and will cause a warning.</li>
        <li>Placing a <a href="../Language.htm#subroutines">subroutine</a> inside another subroutine, breaking the flow of code.</li>
      </ul>
      <p>If the code is intended to be unreachable - such as if a <code>return</code> has been used to temporarily disable a block of code, or a hotkey or hotstring has been temporarily disabled by commenting it out - consider commenting out the unreachable code as well. Alternatively, the warning can be suppressed by defining a <a href="../misc/Labels.htm">label</a> above the first unreachable line.</p>
      <p><strong>All</strong>: Apply the given <em>WarningMode</em> to all supported warning types.</p>
    </dd>

  <dt>WarningMode</dt>
  <dd>
      <p>A value indicating how warnings should be delivered. If omitted, it defaults to <em>MsgBox</em>.</p>
      <p><strong>MsgBox</strong>: Show a message box describing the warning.  Note that once the message box is dismissed, the script will continue as usual.</p>
      <p><strong>StdOut</strong> <span class="ver">[v1.1.04+]</span>: Send a description of the warning to <em>stdout</em> (the program's standard output stream), along with the filename and line number.  This allows fancy editors such as SciTE to capture warnings without disrupting the script - the user can later jump to each offending line via the editor's output pane.</p>
      <p><strong>OutputDebug</strong>: Send a description of the warning to the debugger for display.  If a debugger is not active, this will have no effect.  For more details, see <a href="OutputDebug.htm">OutputDebug</a>.</p>
      <p><strong>Off</strong>: Disable warnings of the given <em>WarningType</em>.</p>
    </dd>

</dl>
<h2>Remarks</h2>
	<p>By default, all warnings are off.</p>
	<p>Warnings can't be enabled or disabled at run-time; the settings are determined when a script loads.  Therefore, the location in the script is not significant (and, like other # directives, #Warn cannot be executed conditionally).</p>
	<p>However, the ordering of multiple #Warn directives is significant: the last occurrence that sets a given warning determines the mode for that warning.  So, for example, the two statements below have the combined effect of enabling all warnings except UseEnv:</p>
<pre>#Warn All
#Warn UseEnv, Off

EnvSet EnvVar, 1
x := EnvVar       <em>; Okay since #NoEnv has not been used.</em>
x := NotAnEnvVar  <em>; Warning.</em>
</pre>
<h2>Related</h2>
<p><a href="../Functions.htm#Local">Local and Global Variables</a></p>
<h2>Examples</h2>
<div class="ex" id="ExBasic">
<p><a href="#ExBasic">#1</a></p>
<pre>
#Warn All, Off                    <em>; Disable all warnings.  This is the default state.</em>
#Warn                             <em>; Enable every type of warning; show each warning in a message box.</em>
#Warn UseUnsetLocal, OutputDebug  <em>; Warn when a local variable is used before it's set; send warning to OutputDebug.</em>
</pre>
</div>

</body>
</html>
